----------------------- 
IAU_UnicodeNamesChecker
----------------------- 

Program instructions prepared by Jim Mosher (jimmosher@yahoo.com), 28 Mar 2011 


-------
PURPOSE
-------

This program is used to verify that the current information regarding named solar system features in an LTVT dot file is consistent with the current information in the IAU Planetary Gazetteer database.  

It can also be used to transfer the current set of user flags (features tagged for display in LTVT when the feature Threshold Diameter is set to -1) to a new set of dot files generated from the current IAU data.  


-----------
INPUT FILES
-----------

1. IAU_UnicodeNamesChecker.exe  -- the program executable, found in the current folder

2. UnicodeSubstitutes.txt - a text file in comma-separated-value (CSV) format listing simple ASCII characters to be used to replace unicode characters with selected numeric codes, found in the current folder

3. The LTVT dot file to be checked.  Dot files, which normally have a "*.csv" extension, are explained at:: 

  http://ltvt.wikispaces.com/Dot+Files 

4. A reference file of current information for the desired target object in "*.TSV" format downloaded from the IAU website under "Advanced Search":

  http://planetarynames.wr.usgs.gov/AdvancedSearch

Although any of the additional fields can be requested, the following IAU fields MUST be included in the .TSV download:

  'Feature ID'
  'Feature Name'
  'Target'
  'Diameter'
  'Center Lat/Lon'
  'Coordinate System'
  'Feature Type Code'
  'Origin'
  'Additional Info'

The Coordinate System requested should be '+East' 'Planetocentric' with a (longitude) range of '-180 to +180' for the Moon and '0 to +360' for all other objects.

Since the names are written to the output files (see below) in the order in which they are encountered in the IAU reference file, it is generally convenient to request that the IAU download be Sorted by 'Feature Name' - 'Ascending' (in which case the output files will be automatically alphabetized).

Also, although multiple target bodies can be included in a single IAU download, it is generally convenient to request a separate file for each 'Target' of interest (Moon, Mercury, Venus, Mars).

Be sure to select 'Output Format' -- 'TSV Tab-separated values (spreadsheet)' before clicking 'Search' to initiate the download.


---------
OPERATION
---------

To operate the program, the buttons in the upper left are used to select the LTVT dot file to be checked, the IAU reference file to which it is to be compared, and the unicode character substitutions file.

If the IAU reference file contains names related to more than one target "planet", the one relevant to the LTVT dot file to be checked should be specified in the box provided.

The checkboxes have the following functions:

  "Restrict to IAU target =" asks the program to ignore entries in the IAU file that are not relevant to the selected planet

  "Generate new LTVT dot files" determines if the Output Files (see below) will be written to disk

  "Check for non-IAU names" determines in the input LTVT dot file will be screen for names not appearing in the IAU list (if encountered, they will be listed on the screen and their data written to a disk file, if disk file output is requested).

  "Display changes below" lists on the screen any discrepancies found between the data in the LTVT dot file and the data IAU reference file.

Once the correct input files and options have been selected, program operation is initiated by clicking the "Process Files" button.

The "Copy" button copies the information in the memo area to the Windows clipboard for pasting into another application.

The "Clear" button clears the memo area.

The internal operation of the program takes place in several passes:

1. The specified list of ASCII substitute characters for problem unicode sequences is read from disk.

2. The specified LTVT dot file is read from disk.

3. The specified IAU .TSV file is read from disk.  The file is in what is called UTF-8 unicode format, which uses a single byte for normal ASCII characters and multiple bytes for more difficult to represent characters.  For use with LTVT, each character is converted to a single-byte ASCII character with a numeric code between 0 and 255. Any unicode sequence for which a substitute is not specified will be listed on the screen.  If the "Restrict to IAU target =" option is selected, lines in the IAU file that are not for that planet will be ignored.

4. Each line in the IAU file is checked against the LTVT dot file to see if the same name is listed there.  If the name is not found, it will be listed on the screen, and in cases where a matching name IS found, any discrepancies will be listed on the screen if the "Display changes below" option has been checked.  If the "Generate new LTVT dot files" option is checked, each line in the IAU file will be used to add a line to one of the output files (see below) to which the current LTVT flag status will be added if a matching LTVT name was found.

5. If requested with the "Check for non-IAU names" option, the program will then read through the LTVT dot file and list on the screen any names it includes that CANNOT be found in the IAU file.  If the "Generate new LTVT dot files" option is checked, these will also be written to "NonIAUnames.csv".


------------
OUTPUT FILES
------------
 
The following output files in LTVT dot file format will appear in the folder containing the program executable when the "Generate new LTVT dot files" option is checked:

1.  Discontinued.csv -- discontinued names (of all types -- indicated by names in [] in IAU file) 
2.  PrimaryCraters.csv -- craters and landing site features (codes "AA" and "LF" for the Moon -- all codes for other planets)   
3.  Satellites.csv -- satellite features (code "SF" = "lettered craters" on the Moon)   
4.  NonCraters.csv -- all other codes
5.  NonIAUnames.csv --  non-IAU names (lines from dot file with names not found in IAU list)

Files 3 & 4 are generated ONLY when the target object is the Earth's Moon. For all other targets, the data for all IAU named features go into file 1 or 2 as appropriate.  File 5 is updated only if the "Check for non-IAU names" option is selected.  For file 4 for the Moon, it may be desired to open the file with Microsoft Excel and to sort it by feature type code, then by feature name, so that features of a given type will be grouped together.

The files written to disk DO NOT include the header line required for a valid LTVT dot file, so one normally copies the header information and comments from the old dot file, then opens the output file with a text processor and pastes the new IAU data lines over the data lines in the old dot file.  

The normal order of assembly for the Moon is File 2 + 4 + 1 + 3.  For other planets the order is normally File 2 + 1.

Whether the lines with non-IAU names should be included in the new dot file depends on the user's purpose.



For further details, please see the accompanying Pascal source files which can be opened with any plain text processor. 

